Mention icon theme in the migration guide

This was requested in #3216.

diff --git a/docs/reference/gtk/migrating-3to4.md b/docs/reference/gtk/migrating-3to4.md
index bae17df96f1452c32a0d9711d904913fe6d337b1..429e7c7421c5efb593b9dd9381e5e8e350222713 100644 (file)
--- a/docs/reference/gtk/migrating-3to4.md
+++ b/docs/reference/gtk/migrating-3to4.md
@@ -220,6 +220,18 @@ replace many uses of gtk_container_add() with equivalent container-specific
 APIs such as gtk_box_pack_start() or gtk_grid_attach(), and thereby reduce
 the amount of work you have to do at the time of the switch.
 
+### Review your use of icon resources
+
+When using icons as resources, the behavior of GTK 4 is different in one
+respect: Icons that are directly in $APP_ID/icons/ are treated as unthemed
+icons, which also means that symbolic icons are not recolored. If you want
+your icon resources to have icon theme semantics, they need to be placed
+into theme subdirectories such as $APP_ID/icons/16x16/actions or
+$APP_ID/icons/scalable/status.
+
+This location works fine in GTK 3 too, so you can prepare for this change
+before switching to GTK 4.
+
 ## Changes that need to be done at the time of the switch
 
 This section outlines porting tasks that you need to tackle when